Saving a Job Object With a Document File(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 2 - Core Printing Features / Using Core Printing Features

Saving a Job Object With a Document File
There are two approaches you can take to saving a job object with its corresponding document. Either you can create a handle in which to store the job object and then flatten the job object into this handle, or you can specify a pointer to a flattening function to flatten the job object and save its data to disk.
When the user chooses the Save or Save As menu command from the File menu, you should save the document and its corresponding job object to disk. To save a job object, you flatten it. To retrieve a job object, you unflatten it. For an introduction to flattening and unflattening QuickDraw GX print objects, see the chapter "Introduction to Printing With QuickDraw GX" in this book.
When a user saves a document, you may prefer to save a job object in a single handle using the GXFlattenJobToHdl function. You may also choose to use the GXFlattenJob function to save a job object. You specify a pointer to a flattening function in this function because it requires less memory to save portions of job object data to disk than it does to save the data in a single handle.

Saving a Job Object in a Single Handle
This section describes how to use the GXFlattenJobToHdl function to save a job object and its related data.
You should create a handle in which to store the job object and then flatten the job object into this handle. You specify a handle in the aHandle parameter to the GXFlattenJobToHdl function. QuickDraw GX grows or shrinks the size of the handle you provide to accommodate the size of the job object. You then save the contents of the handle, typically in the document's resource fork.
Listing 2-7 shows how to save a job object in a document using the GXFlattenJobToHdl function.
Listing 2-7 Using the GXFlattenJobToHdl function to save a job object
OSErr MySaveDocument(MyDocumentPtr myDocument)
{
   OSErr       err;
   Handle      theJobData, oldJobData;
   short       dataRefNum = -1;
   short       oldResFile, resRefNum = -1;
   FSSpec      *docFSSpec;
   
   /* 
      Create a handle in which to store the job object and then 
      flatten the job object into this handle.
   */
   oldResFile = CurResFile();
   theJobData = NewHandle(0);
   err = MemError();
   if (err == noErr)
   {
      GXFlattenJobToHdl(myDocument->documentJob, theJobData);
      err = GXGetJobError(myDocument->documentJob);
      
      if (err == noErr)
      {

         /* Open the file's data fork and resource fork. */
         docFSSpec = &myDocument->documentFSSpec;
         err = FSpOpenDF(docFSSpec, fsRdWrPerm, &dataRefNum);
         if (err == noErr)
         {
            resRefNum = HOpenResFile(docFSSpec->vRefNum, 
                                    docFSSpec->parID,
                                    docFSSpec->name, fsRdWrPerm);
            err = ResError();
         }

         /* Delete any existing job object resources. */
         if (err == noErr)
         {
            UseResFile(resRefNum);
            oldJobData = Get1Resource(kMyJobType, kMyJobID);
            if (oldJobData != nil)
            {
               RmveResource(oldJobData);
               UpdateResFile(resRefNum);
               DisposHandle(oldJobData);
            }

            /* Add the new job object resource. */
            AddResource(theJobData, kMyJobType, kMyJobID, "\p");
            err = ResError();
            if (err == noErr)
            {
               WriteResource(theJobData);
               UpdateResFile(resRefNum);
               ReleaseResource(theJobData);
            }

         /* 
            Write the data for a document's pages to the data
            fork. Place your application-specific code here to
            save page data associated with the document.
         */
         ...
         }

         /* Close the data and resource forks of this document. */
         if (dataRefNum != -1) FSClose(dataRefNum);
         if (resRefNum  != -1) CloseResFile(resRefNum);
      }
      else
         DisposHandle(theJobData);
   }
   UseResFile(oldResFile);
   return err;
}
Saving a Job Object Using a Flattening Function
This section describes how to use the GXFlattenJob function to save a job object. You specify a pointer to a flattening function in the aPrintingFlattenProc parameter of this function.
An example of a flattening function named MyFlattenFunction that you could write is as follows:
OSErr MyFlattenJobFunc(long dataSize, void *data, 
                        void *dataRefNum)
{
   long  count = dataSize;
   return FSWrite((short) dataRefNum, &count, data);
}
QuickDraw GX calls your flattening function multiple times as it saves job object data to disk. The dataSize parameter specifies the number of bytes for this segment of the job object data. The data parameter specifies a pointer to the segments of job object data to write out. The dataRefNum parameter specifies the file reference number of the open file to which you want to write.
Listing 2-8 shows how to save a job object using the GXFlattenJob function.
Listing 2-8 Using the GXFlattenJob function to save a job object
OSErr MySaveJobInDataFork(MyDocumentPtr myDocument, 
                           short dataRefNum)
{
   OSErr    err;

   /*
      Reset the file's position to the beginning of the data fork 
      and write the flattened job object there.
   */
   err = SetFPos(dataRefNum, fsFromStart, 0);
   if (err == noErr)
   {
      GXFlattenJob(myDocument->documentJob,
                    (gxPrintingFlattenProc) MyFlattenJobFunc,
                    dataRefNum);
      err = GXGetJobError(myDocument->documentJob);
   }
   return err;
}